---
title: Signature Pad
description: Using the signature pad component in your application
package: "@zag-js/signature-pad"
---

The signature pad component allows users to draw handwritten signatures using
touch or pointer devices. The signature can be saved as an image or cleared.

<Resources pkg="@zag-js/signature-pad" />

<Showcase id="SignaturePad" />

**Features**

- Draw signatures using touch or pointer devices
- Save the signature as an image
- Clear the signature

## Installation

To use the signature pad machine in your project, run the following command in
your command line:

<CodeSnippet id="signature-pad/installation.mdx" />

## Anatomy

To set up the signature pad correctly, you'll need to understand its anatomy and
how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="signature-pad" />

## Usage

First, import the signature pad package into your project

```jsx
import * as signaturePad from "@zag-js/signature-pad"
```

The signature pad package exports two key functions:

- `machine` — The state machine logic for the signature pad widget.
- `connect` — The function that translates the machine's state to JSX attributes
  and event handlers.

Next, import the required hooks and functions for your framework and use the
signature pad machine in your project 🔥

<CodeSnippet id="signature-pad/usage.mdx" />

### Listening to drawing events

The signature pad component emits the following events:

- `onDraw`: Emitted when the user is drawing the signature.
- `onDrawEnd`: Emitted when the user stops drawing the signature.

```jsx
const service = useMachine(signature.machine, {
  onDraw(details) {
    // details => { path: string[] }
    console.log("Drawing signature", details)
  },
  onDrawEnd(details) {
    // details => { path: string[], toDataURL: () => string }
    console.log("Signature drawn", details)
  },
})
```

### Clearing the signature

To clear the signature, use the `api.clear()`, or render the clear trigger
button.

```jsx
<button onClick={() => api.clear()}>Clear</button>
```

### Rendering an image preview

Use the `api.getDataUrl()` method to get the signature as a data URL and render
it as an image.

> You can also leverage the `onDrawEnd` event to get the signature data URL.

```jsx
const service = useMachine(signature.machine, {
  onDrawEnd(details) {
    details.getDataUrl("image/png").then((url) => {
      // set the image URL in local state
      setImageURL(url)
    })
  },
})
```

Next, render the image preview using the URL.

```jsx
<img src={imageURL} alt="Signature" />
```

### Changing the stroke color

To change the stroke color, set the `drawing.fill` option to a valid CSS color.

> Note: You can't use a css variable as the stroke color.

```jsx
const service = useMachine(signature.machine, {
  drawing: {
    fill: "red",
  },
})
```

### Changing the stroke width

To change the stroke width, set the `drawing.size` option to a number.

```jsx
const service = useMachine(signature.machine, {
  drawing: {
    size: 5,
  },
})
```

### Simulating pressure sensitivity

Pressure sensitivity is disabled by default. To enable it, set the
`drawing.simulatePressure` option to `true`.

```jsx
const service = useMachine(signature.machine, {
  drawing: {
    simulatePressure: true,
  },
})
```

### Usage in forms

To use the signature pad in a form, set the `name` context property.

```jsx
const service = useMachine(signature.machine, {
  name: "signature",
})
```

Then, render the hidden input element using `api.getHiddenInputProps()`.

```jsx
<input {...api.getHiddenInputProps({ value: imageURL })} />
```

### Disabling the signature pad

Set the `disabled` context property to `true` to disable the signature pad.

```jsx
const service = useMachine(signature.machine, {
  disabled: true,
})
```

### Making the signature pad read-only

Set the `readOnly` context property to `true` to make the signature pad
read-only.

```jsx
const service = useMachine(signature.machine, {
  readOnly: true,
})
```

## Methods and Properties

The signature pad `api` exposes the following methods and properties:

### Machine Context

The signature pad machine exposes the following context properties:

<ContextTable name="signature-pad" />

### Machine API

The signature pad `api` exposes the following methods:

<ApiTable name="signature-pad" />

### Data Attributes

<DataAttrTable name="signature-pad" />
